<?php

require_once("finefs/class.FineFS.php");
require_once("finefs/utils/except.ApplicationException.php");
require_once("finefs/utils/except.IOException.php");
require_once("class.FineDBCollection.php");
require_once("class.FineDBDocument.php");

/**
 * Minimal object for the management of FineDB's data collection.
 *
 * @author	Amaury Bouchard <amaury.bouchard@finemedia.fr>
 * @copyright	Copyright (c) 2010, FineMedia
 * @package	FineDB
 * @subpackage	lib
 * @version	$Id: class.FineDBProtoCollection.php 7 2010-09-14 13:03:04Z amaury.bouchard $
 */
class FineDBProtoCollection extends FineDBCollection {
	/* *********************** DOCUMENT MANAGEMENT METHODS ******************* */
	/**
	 * Fetch a document from its identifier.
	 * @param	string	$id	Identifier of the document.
	 * @return	FineDBdocument	An object to manage the document.
	 * @throws	IOException	Problem to get the document.
	 */
	public function get($id) {
		return ($this->_get($id));
	}
	/**
	 * Remove a document.
	 * @param	string	$documentId	Document's identifier.
	 * @throws	IOException	Unknown document.
	 */
	public function removeDocument($documentId) {
		$this->_removeDocument($documentId);
	}
	/**
	 * Create a new document.
	 * @param	mixed	$data	Document's data.
	 * @param	array	$meta	(optional) Document's metadata.
	 * @return	FineDBDocument	An object to manage the new document.
	 * @throws	ApplicationException	Bad parameter.
	 * @throws	IOException		Problem during document creation.
	 */
	public function add($data, $meta=null) {
		return ($this->_add($data, $meta));
	}

	/* *********************** SEARCH METHODS ***************** */
	/**
	 * Returns a list of all documents.
	 * @param	string|array	$sort		(optional) Hash of sort criteria.
	 * @param	int		$limitOffset	(optional) Offset of the first returned document. Can be negative to
	 *						specify an offset from the end of the list. 0 by default.
	 * @param	int		$nbrDocuments	(optional) Number of documents to return. By default, returns all documents after the offset.
	 * @return	array	List of documents' identifiers.
	 */
	public function getList($sort=null, $limitOffset=null, $nbrDocuments=null) {
		return ($this->_getList($sort, $limitOffset, $nbrdocuments));
	}
	/**
	 * Get a document from an unique index.
	 * @param	string	$index	Name of the index.
	 * @param	string	$value	Value of the index.
	 * @return	FineDBDocument	The resulting document.
	 * @throws	ApplicationException	Not a unique index.
	 * @throws	IOException		Read error.
	 */
	public function getFromIndex($index, $value) {
		return ($this->_getFromIndex($index, $value));
	}
	/**
	 * Get a document from some criteria. If many document match these criteria, the first is returned.
	 * @param	array	$criteria	Hash of search criteria.
	 * @return	FineDBDocument	The resulting document.
	 * @throws	ApplicationException	Parameter error.
	 * @throws	IOException		Read error.
	 */
	public function find($criteria) {
		return ($this->_find($criteria));
	}
	/**
	 * Search a list of documents from some criteria.
	 * @param	array		$criteria	Hash of search criteria.
	 * @param	string|array	$sort		(optional) Hash of sort criteria.
	 * @param	int		$limitOffset	(optional) Offset of the first returned document. Can be negative to
	 *						specify an offset from the end of the list. 0 by default.
	 * @param	int		$nbrDocuments	(optional) Number of documents to return. By default, returns all documents after the offset.
	 * @return	array		List of document identifiers.
	 * @throws	ApplicationException	Parameter error.
	 * @throws	IOException		Read error.
	 */
	public function search($criteria, $sort=null, $limitOffset=null, $nbrDocuments=null) {
		return ($this->_search($criteria, $srot, $limitOffset, $nbrDocuments));
	}
}

?>
